using System;
using System.Globalization;

namespace Sedna.Core.Globalization
{
	/// <summary>
	/// service that provides message localization facility
	/// it converts key to a human readable string
	/// Concrete message manager implementation can ctore messages in an XML file
	/// or even in a database
	/// </summary>
	public interface IMessageManager
	{
		/// <summary>
		/// converts a key to a mapped string
		/// </summary>
		/// <param name="key">unique message key, null value may be treated differentrly in different implementaitons, therefore the best practive is to avoid using null keys</param>
		/// <returns>mapped localized string or the key if no string can be found, although some implementation may throw an exception to simplify failing messages identification</returns>
		string GetMessage(string key);

		/// <summary>
		/// the same as above, but accepts a default message value, if a message with a specified key is not found - default value is returned
		/// </summary>
		/// <param name="key">unique message key</param>
		/// <param name="defaultValue">a value to return in case no message under a specified key is found</param>
		/// <returns>either message mapped under a specified key or a default value if none can be found</returns>
		string GetMessage(string key, string defaultValue);

		/// <summary>
		/// the same as above but this method accepts a specified culture to be used instead of a thread default culture.
		/// this is necessary if there is a need to get a message for a culture different from the one set up for a current thread
		/// </summary>
		/// <param name="key">unique message key</param>
		/// <param name="cultureInfo">culture info to be used for message lookup</param>
		/// <returns>localized message for the specified culture or default value </returns>
		string GetMessage(string key, CultureInfo cultureInfo);

		/// <summary>
		/// the same as above but allows specifying a default value that is returned if a corresponding message under the 
		/// specified key cannot be located
		/// </summary>
		/// <param name="key">unique message key</param>
		/// <param name="cultureInfo">culture info that is used for message lookup</param>
		/// <param name="defaultValue">default value that is returned in case if a target message with the specified key is not found</param>
		/// <returns>localized message or default value</returns>
		string GetMessage(string key, CultureInfo cultureInfo, string defaultValue);
	}
}
